Crate r3bl_ansi_color
source ·Expand description
r3bl_ansi_color crate
What does it do?
Rust crate to generate formatted ANSI 256 (8-bit) and truecolor (24-bit) color output to stdout. On macOS, the default Terminal.app does not support truecolor, so ANSI 256 colors are used instead.
This crate performs its own detection of terminal color capability heuristically. And does not use other crates to perform this function.
Here’s a screenshot of running the main
example on various operating systems:
Running on Linux Tilix |
Running on Windows Terminal |
Running on macOS terminal app (note ANSI 256 runtime detection) |
Running on macOS iTerm app (note Truecolor runtime detection) |
How to use it?
The main struct that we have to consider is AnsiStyledText
. It has two fields:
text
- the text to print.style
- a list of styles to apply to the text.
Here’s an example.
use r3bl_ansi_color::{AnsiStyledText, Style, Color};
AnsiStyledText {
text: "Print a formatted (bold, italic, underline) string w/ ANSI color codes.",
style: &[
Style::Bold,
Style::Italic,
Style::Underline,
Style::Foreground(Color::Rgb(50, 50, 50)),
Style::Background(Color::Rgb(100, 200, 1)),
],
}
.println();
Please a look at the
main
example to get a
better idea of how to use this crate.
Build, run, test tasks
Prerequisites
🌠 In order for these to work you have to install the Rust toolchain and just
and
cargo-watch
:
- Install the Rust toolchain using
rustup
by following the instructions here. - Install
cargo-watch
usingcargo install cargo-watch
. - Install
flamegraph
usingcargo install flamegraph
. - Install
just
just
on your system usingcargo install just
. It is available for Linux, macOS, and Windows.- If you want shell completions for
just
you can follow these instructions. - If you install
just
usingcargo install just
orbrew install just
you will not get shell completions without doing one extra configuration step. So on Linux it is best to usesudo apt install -y just
if you want them.
- If you want shell completions for
Just commands
- Build:
just build
- Clean:
just clean
- Run examples:
just run
- Run examples with release flag:
just run-release
- Run examples with flamegraph profiling:
just run-flamegraph
- Run tests:
just test
- Run clippy:
just clippy
- Build docs:
just docs
- Serve docs:
just serve-docs
. This is only useful if you SSH into a remote machine via VSCode (where you build and serve the docs) and want to view the docs in a browser on your local machine. - Upgrade deps:
just upgrade-deps
- Run rustfmt:
just rustfmt
The following commands will watch for changes in the source folder and re-run:
- Watch run:
just watch-run
- Watch all test:
just watch-all-tests
- Watch one test:
just watch-one-test <test_name>
- Watch clippy:
just watch-clippy
- Watch macro expansion for one test:
just watch-macro-expansion-one-test <test_name>
References
- https://notes.burke.libbey.me/ansi-escape-codes/
- https://www.asciitable.com/
- https://commons.wikimedia.org/wiki/File:Xterm_256color_chart.svg
- https://www.ditig.com/256-colors-cheat-sheet
- https://stackoverflow.com/questions/4842424/list-of-ansi-color-escape-sequences
- https://www.compuphase.com/cmetric.htm
Why make a new crate for this?
- There are a few crates on crates.io that do similar things but they don’t amenable licenses.
- Other crates simply ignore ANSI 256 colors and only support truecolor, even when they claim that they support it.
- And there are other crates which don’t correctly report that macOS Terminal.app does not support truecolor and only supports ANSI 256 color.
Here are some links:
- https://github.com/rust-cli/concolor/issues/47
- https://docs.rs/anstream/latest/anstream/
- https://docs.rs/colorchoice/latest/colorchoice/
- https://docs.rs/colorchoice-clap/latest/colorchoice_clap/
- https://docs.rs/anstyle-query/latest/anstyle_query/fn.term_supports_ansi_color.html
- https://crates.io/crates/anstyle-query
- https://docs.rs/supports-color/2.0.0/supports_color/
- https://crates.io/crates/r3bl_ansi_color (the source in
ansi_color
folder is this crate) - https://crates.io/crates/colored
Re-exports
pub use ansi_escape_codes::*;
pub use ansi_styled_text::*;
pub use color::*;
pub use convert::*;
pub use detect_color_support::*;
Modules
- More info:
- More info:
- More info: